Share specs, Not execution

Swagger and Postman, the Iron Man and Captain America of the API world, are bound to work on the same team despite their inherent incompatibilities. With the right oversight, they can work together like a charm, each bringing their own superpowers to the table.

Swagger: The Documentarian

Swagger is like that meticulous librarian who keeps everything cataloged and easily accessible. It hosts the definition of your API along with all the documents. You feed it your request bodies, query params, authorizers, response bodies, and error handlers, and voilà! Swagger serves up a playable prototype of your API for anyone to tinker with.

Postman: The Mad Scientist

On the other hand, Postman is the mad scientist of API testing. It’s where you can let your imagination run wild, chaining API outputs to inputs, concocting elaborate test scenarios, and basically doing things that would make Swagger raise an eyebrow (if it had one).

The Golden Rule: Share the Specs, Not the Execution

Here’s where things get interesting. Both Swagger and Postman allow you to share API definitions, usually in the form of a JSON file that adheres to the OpenAPI spec (not to be confused with OpenAI – though wouldn’t it be fun if our APIs could generate themselves?). You upload this JSON, and boom! Your API definition is out there for the world to see.

But here’s the kicker: with Swagger, what happens in Vegas stays in Vegas. You can provide wrong tokens, push the API to its limits, and generally make a mess, but it’s all contained within your own little sandbox. Open a new tab, and it’s like starting with a clean slate. Your chaos doesn’t affect anyone else’s experience.

Postman, however, is more of a “what’s mine is yours” kind of tool. In shared collections, everything syncs faster than you can say “API.” Your tokens, variables, examples – they’re all up for grabs. It’s like having roommates who use your toothbrush without asking.

A Tale of Two Approaches

Let me take you on a journey through time, spanning about 10-14 months, that showcases the evolution of our relationship with these tools.

Back in the day, I was a mobile engineer, and Swagger was our go-to for API definitions. The backend team was always ahead, it a policy that REST APIs should be stable before UI team starts consuming them¹. My job? Play around with these APIs like a kid in a candy store, making sure they could handle whatever data our mobile apps threw at them. But here’s the catch – sometimes the Swagger docs and the actual code were as different as chalk and cheese.

Fast forward about a year, and our entire team of seasoned mobile engineers had metamorphosed into backend developers. We embraced the serverless lifestyle, and it took us a good chunk of time for us to craft our first set of APIs for the newly formed UI teams.

Here’s where we did the thing differently, backed by serverless and their set of API to automate a lot of things. We’d pass API models to API Gateway, run a script to generate Swagger docs, and deploy them to a portal faster than you can say “API synchronization.” Suddenly, our frontend team had up-to-date API definitions quicker than you could order a pizza. We even started generating Postman collection JSONs for those who preferred their API definitions with a side of Postman.

But let me tell you about another organization I worked with – they were Postman zealots. Swagger? Banned. We were knee-deep in a project that would be scrutinized by external teams for regulatory reasons.. (no pressure, right?).

One day, a long-time engineer decided to play mad scientist. They added a token passing mechanism as a collection variable, sneakily embedding it in the collection definition. Did they tell anyone? Of course not. That would be too easy.

Fast forward a week, and I’m back from working on a different project. Suddenly, all my APIs are throwing tantrums, I didn’t expect that they would grow up that quickly. It took me days to realize that the tokens I was passing were getting hijacked by this sneaky collection variable.

After some heated debates and a few veto threats, I ended up creating a private copy, purged of these changes, just so I could get back to work. The kicker? This broke a whole workflow I had set up based on login and profile responses. All because someone decided to play token roulette without sending a memo.

The Postman Predicament

Postman starts with a blank canvas, letting you craft requests by hand – URLs, headers, body, the works. It’s powerful and flexible, like a Swiss Army knife for APIs. But with great power comes great confusion. The possibilities are endless, which is both a blessing and a curse.

Swagger, on the other hand, gives you a set menu of APIs. It’s like API training wheels – great for getting started, but lacking when you want to do fancy tricks. Want to create a resource, get it, pass it to another resource, update it, and check if it changed something else? In Swagger, that’s a manual labor of love. In Postman, it’s a bit less of a headache.

The Ideal Solution

Neither tool is perfect (perfection is overrated anyway); they each have their strengths.While Swagger naturally aligns with our golden rule of ‘share the specs, not the execution’, it can’t quite match Postman’s utility and flexibility. The ideal solution would combine Swagger’s philosophy with Postman’s powerful features without avoiding the nightmare postman can create.²

Until then, we’ll keep juggling these tools, appreciating their strengths and working around their quirks. Because at the end of the day, that’s what being a developer is all about – making the best of what we’ve got and dreaming of that perfect tool that’s always just one more feature away.

So, the next time you’re knee-deep in API development, remember: share the specs, not the execution. Your future self (and your team) will thank you. And who knows? Maybe one day we’ll have a tool that combines the best of both worlds – the Iron Man suit with Captain America’s shield, if you will. Now that would be a superhero worth waiting for in the API universe.

Until this superhero appears…

May the force be with you…